/*
 *   This program is free software: you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License as published by
 *   the Free Software Foundation, either version 3 of the License, or
 *   (at your option) any later version.
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

/*
 * SimulatedAnnealing.java
 * Copyright (C) 2004-2012 University of Waikato, Hamilton, New Zealand
 * 
 */

package weka.classifiers.bayes.net.search.global;

import java.util.Collections;
import java.util.Enumeration;
import java.util.Random;
import java.util.Vector;

import weka.classifiers.bayes.BayesNet;
import weka.core.Instances;
import weka.core.Option;
import weka.core.TechnicalInformation;
import weka.core.TechnicalInformation.Field;
import weka.core.TechnicalInformation.Type;
import weka.core.TechnicalInformationHandler;
import weka.core.Utils;

/**
 * <!-- globalinfo-start --> This Bayes Network learning algorithm uses the
 * general purpose search method of simulated annealing to find a well scoring
 * network structure.<br/>
 * <br/>
 * For more information see:<br/>
 * <br/>
 * R.R. Bouckaert (1995). Bayesian Belief Networks: from Construction to
 * Inference. Utrecht, Netherlands.
 * <p/>
 * <!-- globalinfo-end -->
 * 
 * <!-- technical-bibtex-start --> BibTeX:
 * 
 * <pre>
 * &#64;phdthesis{Bouckaert1995,
 *    address = {Utrecht, Netherlands},
 *    author = {R.R. Bouckaert},
 *    institution = {University of Utrecht},
 *    title = {Bayesian Belief Networks: from Construction to Inference},
 *    year = {1995}
 * }
 * </pre>
 * <p/>
 * <!-- technical-bibtex-end -->
 * 
 * <!-- options-start --> Valid options are:
 * <p/>
 * 
 * <pre>
 * -A &lt;float&gt;
 *  Start temperature
 * </pre>
 * 
 * <pre>
 * -U &lt;integer&gt;
 *  Number of runs
 * </pre>
 * 
 * <pre>
 * -D &lt;float&gt;
 *  Delta temperature
 * </pre>
 * 
 * <pre>
 * -R &lt;seed&gt;
 *  Random number seed
 * </pre>
 * 
 * <pre>
 * -mbc
 *  Applies a Markov Blanket correction to the network structure, 
 *  after a network structure is learned. This ensures that all 
 *  nodes in the network are part of the Markov blanket of the 
 *  classifier node.
 * </pre>
 * 
 * <pre>
 * -S [LOO-CV|k-Fold-CV|Cumulative-CV]
 *  Score type (LOO-CV,k-Fold-CV,Cumulative-CV)
 * </pre>
 * 
 * <pre>
 * -Q
 *  Use probabilistic or 0/1 scoring.
 *  (default probabilistic scoring)
 * </pre>
 * 
 * <!-- options-end -->
 * 
 * @author Remco Bouckaert (rrb@xm.co.nz)
 * @version $Revision$
 */
public class SimulatedAnnealing extends GlobalScoreSearchAlgorithm implements TechnicalInformationHandler {

    /** for serialization */
    static final long serialVersionUID = -5482721887881010916L;

    /** start temperature **/
    double m_fTStart = 10;

    /** change in temperature at every run **/
    double m_fDelta = 0.999;

    /** number of runs **/
    int m_nRuns = 10000;

    /** use the arc reversal operator **/
    boolean m_bUseArcReversal = false;

    /** random number seed **/
    int m_nSeed = 1;

    /** random number generator **/
    Random m_random;

    /**
     * Returns an instance of a TechnicalInformation object, containing detailed
     * information about the technical background of this class, e.g., paper
     * reference or book this class is based on.
     * 
     * @return the technical information about this class
     */
    @Override
    public TechnicalInformation getTechnicalInformation() {
        TechnicalInformation result;

        result = new TechnicalInformation(Type.PHDTHESIS);
        result.setValue(Field.AUTHOR, "R.R. Bouckaert");
        result.setValue(Field.YEAR, "1995");
        result.setValue(Field.TITLE, "Bayesian Belief Networks: from Construction to Inference");
        result.setValue(Field.INSTITUTION, "University of Utrecht");
        result.setValue(Field.ADDRESS, "Utrecht, Netherlands");

        return result;
    }

    /**
     * 
     * @param bayesNet  the bayes net to use
     * @param instances the data to use
     * @throws Exception if something goes wrong
     */
    @Override
    public void search(BayesNet bayesNet, Instances instances) throws Exception {
        m_random = new Random(m_nSeed);

        // determine base scores
        double fCurrentScore = calcScore(bayesNet);

        // keep track of best scoring network
        double fBestScore = fCurrentScore;
        BayesNet bestBayesNet = new BayesNet();
        bestBayesNet.m_Instances = instances;
        bestBayesNet.initStructure();
        copyParentSets(bestBayesNet, bayesNet);

        double fTemp = m_fTStart;
        for (int iRun = 0; iRun < m_nRuns; iRun++) {
            boolean bRunSucces = false;
            double fDeltaScore = 0.0;
            while (!bRunSucces) {
                // pick two nodes at random
                int iTailNode = m_random.nextInt(instances.numAttributes());
                int iHeadNode = m_random.nextInt(instances.numAttributes());
                while (iTailNode == iHeadNode) {
                    iHeadNode = m_random.nextInt(instances.numAttributes());
                }
                if (isArc(bayesNet, iHeadNode, iTailNode)) {
                    bRunSucces = true;
                    // either try a delete
                    bayesNet.getParentSet(iHeadNode).deleteParent(iTailNode, instances);
                    double fScore = calcScore(bayesNet);
                    fDeltaScore = fScore - fCurrentScore;
                    // System.out.println("Try delete " + iTailNode + "->" + iHeadNode +
                    // " dScore = " + fDeltaScore);
                    if (fTemp * Math.log((Math.abs(m_random.nextInt()) % 10000) / 10000.0 + 1e-100) < fDeltaScore) {
                        // System.out.println("success!!!");
                        fCurrentScore = fScore;
                    } else {
                        // roll back
                        bayesNet.getParentSet(iHeadNode).addParent(iTailNode, instances);
                    }
                } else {
                    // try to add an arc
                    if (addArcMakesSense(bayesNet, instances, iHeadNode, iTailNode)) {
                        bRunSucces = true;
                        double fScore = calcScoreWithExtraParent(iHeadNode, iTailNode);
                        fDeltaScore = fScore - fCurrentScore;
                        // System.out.println("Try add " + iTailNode + "->" + iHeadNode +
                        // " dScore = " + fDeltaScore);
                        if (fTemp * Math.log((Math.abs(m_random.nextInt()) % 10000) / 10000.0 + 1e-100) < fDeltaScore) {
                            // System.out.println("success!!!");
                            bayesNet.getParentSet(iHeadNode).addParent(iTailNode, instances);
                            fCurrentScore = fScore;
                        }
                    }
                }
            }
            if (fCurrentScore > fBestScore) {
                copyParentSets(bestBayesNet, bayesNet);
            }
            fTemp = fTemp * m_fDelta;
        }

        copyParentSets(bayesNet, bestBayesNet);
    } // buildStructure

    /**
     * CopyParentSets copies parent sets of source to dest BayesNet
     * 
     * @param dest   destination network
     * @param source source network
     */
    void copyParentSets(BayesNet dest, BayesNet source) {
        int nNodes = source.getNrOfNodes();
        // clear parent set first
        for (int iNode = 0; iNode < nNodes; iNode++) {
            dest.getParentSet(iNode).copy(source.getParentSet(iNode));
        }
    } // CopyParentSets

    /**
     * @return double
     */
    public double getDelta() {
        return m_fDelta;
    }

    /**
     * @return double
     */
    public double getTStart() {
        return m_fTStart;
    }

    /**
     * @return int
     */
    public int getRuns() {
        return m_nRuns;
    }

    /**
     * Sets the m_fDelta.
     * 
     * @param fDelta The m_fDelta to set
     */
    public void setDelta(double fDelta) {
        m_fDelta = fDelta;
    }

    /**
     * Sets the m_fTStart.
     * 
     * @param fTStart The m_fTStart to set
     */
    public void setTStart(double fTStart) {
        m_fTStart = fTStart;
    }

    /**
     * Sets the m_nRuns.
     * 
     * @param nRuns The m_nRuns to set
     */
    public void setRuns(int nRuns) {
        m_nRuns = nRuns;
    }

    /**
     * @return random number seed
     */
    public int getSeed() {
        return m_nSeed;
    } // getSeed

    /**
     * Sets the random number seed
     * 
     * @param nSeed The number of the seed to set
     */
    public void setSeed(int nSeed) {
        m_nSeed = nSeed;
    } // setSeed

    /**
     * Returns an enumeration describing the available options.
     * 
     * @return an enumeration of all the available options.
     */
    @Override
    public Enumeration<Option> listOptions() {
        Vector<Option> newVector = new Vector<Option>(4);

        newVector.addElement(new Option("\tStart temperature", "A", 1, "-A <float>"));
        newVector.addElement(new Option("\tNumber of runs", "U", 1, "-U <integer>"));
        newVector.addElement(new Option("\tDelta temperature", "D", 1, "-D <float>"));
        newVector.addElement(new Option("\tRandom number seed", "R", 1, "-R <seed>"));

        newVector.addAll(Collections.list(super.listOptions()));

        return newVector.elements();
    }

    /**
     * Parses a given list of options.
     * <p/>
     * 
     * <!-- options-start --> Valid options are:
     * <p/>
     * 
     * <pre>
     * -A &lt;float&gt;
     *  Start temperature
     * </pre>
     * 
     * <pre>
     * -U &lt;integer&gt;
     *  Number of runs
     * </pre>
     * 
     * <pre>
     * -D &lt;float&gt;
     *  Delta temperature
     * </pre>
     * 
     * <pre>
     * -R &lt;seed&gt;
     *  Random number seed
     * </pre>
     * 
     * <pre>
     * -mbc
     *  Applies a Markov Blanket correction to the network structure, 
     *  after a network structure is learned. This ensures that all 
     *  nodes in the network are part of the Markov blanket of the 
     *  classifier node.
     * </pre>
     * 
     * <pre>
     * -S [LOO-CV|k-Fold-CV|Cumulative-CV]
     *  Score type (LOO-CV,k-Fold-CV,Cumulative-CV)
     * </pre>
     * 
     * <pre>
     * -Q
     *  Use probabilistic or 0/1 scoring.
     *  (default probabilistic scoring)
     * </pre>
     * 
     * <!-- options-end -->
     * 
     * @param options the list of options as an array of strings
     * @throws Exception if an option is not supported
     */
    @Override
    public void setOptions(String[] options) throws Exception {
        String sTStart = Utils.getOption('A', options);
        if (sTStart.length() != 0) {
            setTStart(Double.parseDouble(sTStart));
        }
        String sRuns = Utils.getOption('U', options);
        if (sRuns.length() != 0) {
            setRuns(Integer.parseInt(sRuns));
        }
        String sDelta = Utils.getOption('D', options);
        if (sDelta.length() != 0) {
            setDelta(Double.parseDouble(sDelta));
        }
        String sSeed = Utils.getOption('R', options);
        if (sSeed.length() != 0) {
            setSeed(Integer.parseInt(sSeed));
        }
        super.setOptions(options);
    }

    /**
     * Gets the current settings of the search algorithm.
     * 
     * @return an array of strings suitable for passing to setOptions
     */
    @Override
    public String[] getOptions() {

        Vector<String> options = new Vector<String>();

        options.add("-A");
        options.add("" + getTStart());

        options.add("-U");
        options.add("" + getRuns());

        options.add("-D");
        options.add("" + getDelta());

        options.add("-R");
        options.add("" + getSeed());

        Collections.addAll(options, super.getOptions());

        return options.toArray(new String[0]);
    }

    /**
     * This will return a string describing the classifier.
     * 
     * @return The string.
     */
    @Override
    public String globalInfo() {
        return "This Bayes Network learning algorithm uses the general purpose search method " + "of simulated annealing to find a well scoring network structure.\n\n" + "For more information see:\n\n" + getTechnicalInformation().toString();
    } // globalInfo

    /**
     * @return a string to describe the TStart option.
     */
    public String TStartTipText() {
        return "Sets the start temperature of the simulated annealing search. " + "The start temperature determines the probability that a step in the 'wrong' direction in the " + "search space is accepted. The higher the temperature, the higher the probability of acceptance.";
    } // TStartTipText

    /**
     * @return a string to describe the Runs option.
     */
    public String runsTipText() {
        return "Sets the number of iterations to be performed by the simulated annealing search.";
    } // runsTipText

    /**
     * @return a string to describe the Delta option.
     */
    public String deltaTipText() {
        return "Sets the factor with which the temperature (and thus the acceptance probability of " + "steps in the wrong direction in the search space) is decreased in each iteration.";
    } // deltaTipText

    /**
     * @return a string to describe the Seed option.
     */
    public String seedTipText() {
        return "Initialization value for random number generator." + " Setting the seed allows replicability of experiments.";
    } // seedTipText

} // SimulatedAnnealing
